Installation de Symfony UX
Mise en place de Symfony UX, pas à pas dans un projet vierge
Notions théoriques
Ce qui se passe lors de l'installation de Symfony UX
Installer Symfony UX ne se résume pas à exécuter une commande Composer.
L'installation de Symfony UX un processus en plusieurs couches qui implique à la fois l'écosystème PHP et l'écosystème JavaScript.
Comprendre ce qui se passe, à chaque étape de l'installation de Symfony UX, permet de diagnostiquer les problèmes et d'éviter les erreurs classiques.
Voici les grandes étapes que l'on va détailler :
- Créer un projet Symfony vierge
- Installer le bundle Stimulus (base de Symfony UX)
- Configurer AssetMapper (le gestionnaire d'assets moderne)
- Installer un premier composant UX
- Vérifier que tout fonctionne
Prérequis sur Windows
Avant de commencer, plusieurs outils doivent être disponibles sur la machine :
PHP 8.1 minimum Symfony UX requiert PHP 8.1 ou supérieur. Sur Windows, PHP peut être installé via XAMPP, Laragon, ou directement depuis https://windows.php.net/download.
Composer Composer est le gestionnaire de dépendances PHP. Il est indispensable pour installer Symfony et ses composants. Téléchargement : https://getcomposer.org/Composer-Setup.exe.
Symfony CLI (recommandé) Le CLI Symfony facilite la création de projets et le lancement d'un serveur de développement local. Téléchargement : https://symfony.com/download.
Git Git est nécessaire pour que Composer puisse récupérer certains packages. Téléchargement : https://git-scm.com/download/win.
Sur Windows, après chaque installation d'un outil en ligne de commande (PHP, Composer, Symfony CLI), il faut fermer et rouvrir le terminal pour que les nouvelles variables d'environnement soient prises en compte.
Le rôle de Symfony Flex dans l'installation
Symfony Flex est un plugin Composer installé automatiquement dans tout projet Symfony. Son rôle est d'exécuter des recettes (recipes) lors de l'installation de packages.
Concrètement, quand on exécute composer require symfony/ux-chartjs, Symfony Flex :
- Télécharge le package PHP
- Installe automatiquement le package JavaScript associé (
@symfony/ux-chartjs) - Met à jour le fichier
assets/controllers.jsonpour activer le contrôleur Stimulus - Peut créer ou modifier des fichiers de configuration
Les recettes Symfony Flex sont hébergées sur https://flex.symfony.com. On peut y consulter exactement ce que chaque recette modifie dans un projet.
AssetMapper : le gestionnaire d'assets moderne
Depuis Symfony 6.3, AssetMapper est la solution recommandée pour gérer les fichiers JavaScript et CSS. Il remplace Webpack Encore dans les nouveaux projets.
Son fonctionnement est radicalement différent de Webpack :
| Webpack Encore | AssetMapper |
|---|---|
| Nécessite Node.js | Ne nécessite pas Node.js |
| Compile et bundle les fichiers JS | Sert les fichiers JS directement |
| Étape de build obligatoire | Pas d'étape de build |
| Configuration complexe | Configuration minimale |
| Supporte JSX, Vue SFC, TypeScript | Supporte JavaScript moderne (ESM) |
AssetMapper exploite les Import Maps, une fonctionnalité native des navigateurs modernes qui permet d'importer des modules JavaScript sans bundler.
Pour vérifier que votre navigateur supporte les Import Maps, consultez https://caniuse.com/import-maps. Tous les navigateurs modernes (Chrome, Firefox, Safari, Edge) les supportent depuis 2023.
La structure des assets dans un projet Symfony UX
Après installation de Symfony UX avec AssetMapper, voici les fichiers clés à connaître :
assets/
├── app.js ← Point d'entrée JavaScript principal
├── controllers/ ← Vos contrôleurs Stimulus personnalisés
│ └── hello_controller.js ← Exemple de contrôleur
├── controllers.json ← Déclaration des contrôleurs UX tiers
└── styles/
└── app.css ← Feuille de style principale
config/
└── packages/
└── asset_mapper.yaml ← Configuration d'AssetMapper
importmap.php ← Déclaration des dépendances JavaScript (équivalent package.json)
Le fichier controllers.json est particulièrement important : c'est lui qui active ou désactive les contrôleurs Stimulus fournis par les composants UX installés.
Le fichier importmap.php est l'équivalent du package.json pour AssetMapper. Il liste les dépendances JavaScript et leurs URLs CDN.
Contrairement à Webpack Encore, AssetMapper ne crée pas de dossier node_modules. Les dépendances JavaScript sont soit téléchargées localement dans assets/vendor/, soit référencées via un CDN dans importmap.php.
Le fichier app.js et le bootstrap de Stimulus
Le fichier assets/app.js est le point d'entrée de l'application JavaScript. Dans un projet Symfony UX, il contient typiquement :
import './bootstrap.js';
import './styles/app.css';
Et le fichier assets/bootstrap.js (généré automatiquement) initialise Stimulus :
import { startStimulusApp } from '@symfony/stimulus-bundle';
const app = startStimulusApp();
C'est cette ligne qui démarre le moteur Stimulus et charge tous les contrôleurs déclarés dans controllers.json ainsi que ceux présents dans le dossier assets/controllers/.
Si le fichier bootstrap.js n'importe pas startStimulusApp, aucun contrôleur Stimulus ne fonctionnera, qu'il soit personnalisé ou fourni par un composant UX. C'est l'une des erreurs les plus fréquentes lors d'une installation manuelle.
Les 2 façons d'installer Symfony UX
Option 1 — Projet vierge avec AssetMapper (recommandée)
symfony new mon-projet --webapp
cd mon-projet
composer require symfony/ux-stimulus-bundle
La commande --webapp crée un projet Symfony complet avec Twig, Doctrine, et AssetMapper préconfigurés.
Option 2 — Ajout à un projet existant avec Webpack Encore
composer require symfony/webpack-encore-bundle
npm install
composer require symfony/ux-stimulus-bundle
npm install --force
Dans ce cours, nous travaillons avec AssetMapper (option 1), qui est la méthode recommandée pour les nouveaux projets depuis Symfony 6.3.
Test de mémorisation/compréhension
TP pour réfléchir et résoudre des problèmes
L'objectif de ce TP est d'installer Symfony UX dans un projet vierge, en suivant chaque étape de configuration jusqu'à obtenir une page de test fonctionnelle avec le composant Chart.js opérationnel.
Étape 1 — Vérifier les prérequis
Avant de créer le projet, vérifiez que tous les outils nécessaires sont disponibles sur votre machine Windows.
Ouvrez VS Code, puis ouvrez un terminal et exécutez successivement les commandes suivantes :
php --version
composer --version
symfony version
git --version
Pour chaque commande, notez la version affichée. Si l'une d'elles n'est pas reconnue, installez l'outil manquant avant de continuer.
Une solution
Voici les sorties attendues pour chaque commande (les numéros de version peuvent différer) :
php --version
→ PHP 8.2.12 (cli) (built: ...) ...
composer --version
→ Composer version 2.7.1 ...
symfony version
→ Symfony CLI version 5.x.x
git --version
→ git version 2.44.0.windows.1
Si php n'est pas reconnu, vérifiez que le chemin vers PHP est bien dans la variable d'environnement PATH :
- Ouvrir le menu Démarrer et rechercher "Variables d'environnement"
- Cliquer sur "Modifier les variables d'environnement système"
- Dans "Variables système", sélectionner
Path→ "Modifier" - Vérifier la présence du chemin vers PHP (ex.
C:\phpouC:\laragon\bin\php\php8.2) - Ajouter le chemin si absent, puis cliquer sur OK
- Fermer et rouvrir le terminal
Si symfony n'est pas reconnu, télécharger le CLI depuis https://symfony.com/download et relancer le terminal après installation.
Si composer n'est pas reconnu, télécharger l'installeur depuis https://getcomposer.org/Composer-Setup.exe.
Étape 2 — Créer le projet Symfony dans le dossier Documents
Dans le terminal de VS Code, naviguez vers votre dossier Documents et créez le projet Symfony :
cd %USERPROFILE%\Documents
symfony new tp-symfony-ux --webapp
cd tp-symfony-ux
code .
Attendez la fin de la création du projet (cela peut prendre une à deux minutes selon votre connexion), puis vérifiez que VS Code s'ouvre bien sur le nouveau dossier tp-symfony-ux.
Une solution
La commande cd %USERPROFILE%\Documents vous place dans C:\Users\VotreNom\Documents sur Windows. C'est l'équivalent de ~/Documents sous Linux/macOS.
La commande symfony new tp-symfony-ux --webapp crée un projet Symfony complet. Le flag --webapp installe automatiquement :
- Twig (moteur de templates)
- Doctrine (ORM pour la base de données)
- AssetMapper (gestionnaire d'assets)
- Le bundle Stimulus (base de Symfony UX)
À la fin de la création, le terminal affiche quelque chose comme :
[OK] Your project is now ready in C:\Users\VotreNom\Documents\tp-symfony-ux
La commande code . ouvre VS Code dans ce dossier. Si VS Code ne s'ouvre pas, ouvrez-le manuellement via "Fichier → Ouvrir un dossier" et sélectionnez Documents\tp-symfony-ux.
L'arborescence visible dans l'explorateur VS Code doit contenir notamment les dossiers assets/, config/, src/, templates/, ainsi que les fichiers importmap.php et .env à la racine.
Étape 3 — Vérifier la configuration d'AssetMapper
Dans VS Code, ouvrez successivement les fichiers suivants et vérifiez leur contenu :
Fichier 1 : config/packages/asset_mapper.yaml
Fichier 2 : importmap.php (à la racine du projet)
Fichier 3 : assets/app.js
Fichier 4 : assets/bootstrap.js
Pour chaque fichier, notez ce qu'il contient et comprenez son rôle avant de passer à l'étape suivante.
Une solution
config/packages/asset_mapper.yaml doit contenir :
framework:
asset_mapper:
paths:
- assets/
Ce fichier indique à AssetMapper de surveiller le dossier assets/ pour y trouver les fichiers JavaScript et CSS à servir.
importmap.php doit contenir au minimum :
<?php
return [
'app' => [
'path' => './assets/app.js',
'entrypoint' => true,
],
'@hotwired/stimulus' => [
'version' => '3.2.2',
],
'@symfony/stimulus-bundle' => [
'path' => './vendor/symfony/stimulus-bundle/assets/dist/loader.js',
],
'@hotwired/turbo' => [
'version' => '7.3.0',
],
];
Ce fichier est l'équivalent de package.json pour AssetMapper. Il liste les dépendances JavaScript du projet.
assets/app.js doit contenir :
import './bootstrap.js';
C'est le point d'entrée JavaScript. Il importe bootstrap.js qui démarre Stimulus.
assets/bootstrap.js doit contenir :
import { startStimulusApp } from '@symfony/stimulus-bundle';
const app = startStimulusApp();
La fonction startStimulusApp() démarre le moteur Stimulus et charge automatiquement tous les contrôleurs déclarés dans controllers.json ainsi que ceux présents dans assets/controllers/.
Si l'un de ces fichiers est absent ou différent, c'est un signe que l'installation du projet est incomplète. Dans ce cas, supprimez le dossier et recommencez l'étape 2.
Étape 4 — Configurer la connexion à MariaDB
Ouvrez le fichier .env à la racine du projet. Recherchez la ligne commençant par DATABASE_URL= et modifiez-la pour correspondre à votre installation MariaDB locale.
Pour connaître votre version exacte de MariaDB, exécutez dans le terminal :
mysql --version
Notez le numéro de version affiché, puis adaptez la ligne DATABASE_URL en conséquence. Créez ensuite la base de données avec la commande appropriée.
Une solution
La commande mysql --version retourne quelque chose comme :
mysql Ver 15.1 Distrib 10.11.2-MariaDB, for Win64 (AMD64)
Le numéro de version à retenir ici est 10.11.2-MariaDB.
Ouvrez .env et modifiez la ligne DATABASE_URL :
DATABASE_URL="mysql://root:@127.0.0.1:3306/tp_symfony_ux?serverVersion=10.11.2-MariaDB&charset=utf8mb4"
Points importants :
root: nom d'utilisateur MariaDB (par défaut sous Laragon):suivi de rien : mot de passe vide (par défaut sous Laragon). Si vous avez un mot de passe, écrivezroot:votre_mot_de_passe@tp_symfony_ux: nom de la base de données qui sera créée10.11.2-MariaDB: à remplacer par votre version exacte
Créez ensuite la base de données :
php bin/console doctrine:database:create
Le terminal doit afficher :
Created database `tp_symfony_ux` for connection named default
Si vous obtenez une erreur de connexion, vérifiez que MariaDB (ou Laragon) est bien démarré et que les identifiants dans DATABASE_URL sont corrects.
Étape 5 — Installer le composant ux-twig-component
Installez le composant ux-twig-component via Composer et observez attentivement ce que Symfony Flex affiche dans le terminal pendant l'installation.
composer require symfony/ux-twig-component
Une fois l'installation terminée, ouvrez le fichier assets/controllers.json et notez son contenu.
Une solution
Pendant l'exécution de la commande, Symfony Flex affiche des messages indiquant l'exécution de la recette :
- Configuring symfony/ux-twig-component (>=2.13): From auto-generated recipe
Le fichier assets/controllers.json après cette installation ressemble à :
{
"controllers": [],
"entrypoints": []
}
ou reste inchangé, car ux-twig-component est un composant PHP pur qui n'a pas de contrôleur Stimulus associé. Il ajoute uniquement la possibilité de créer des composants Twig réutilisables côté PHP, sans interaction JavaScript.
Ce comportement est normal et attendu. Le fichier controllers.json n'est mis à jour que pour les composants UX qui apportent un contrôleur Stimulus (comme ux-chartjs, ux-dropzone, etc.).
Étape 6 — Installer le composant ux-chartjs
Installez maintenant le composant ux-chartjs et vérifiez les modifications apportées automatiquement par Symfony Flex dans deux fichiers clés.
composer require symfony/ux-chartjs
Une fois l'installation terminée, ouvrez et comparez le contenu de assets/controllers.json et de importmap.php par rapport à leur état précédent.
Une solution
Vous devez être connecté pour voir le contenu.
Étape 7 — Créer une page de test et lancer le serveur
Créez un contrôleur Symfony dédié aux tests, vérifiez que le template généré étend bien base.html.twig, puis lancez le serveur de développement et accédez à la page dans votre navigateur.
php bin/console make:controller TestController
Après la génération, ouvrez templates/base.html.twig et vérifiez la présence de la balise {{ importmap('app') }} dans le <head>. Lancez ensuite le serveur :
symfony server:start
Accédez à https://127.0.0.1:8000/test et ouvrez la console du navigateur avec F12 pour vérifier l'absence d'erreurs JavaScript.
Une solution
Vous devez être connecté pour voir le contenu.
Étape 8 — Confirmer que Chart.js est bien chargé
Pour valider que le composant ux-chartjs est réellement opérationnel et non simplement installé, inspectez le code source de la page depuis le navigateur et identifiez la balise <script> qui charge le contrôleur Stimulus de Chart.js.
Dans votre navigateur, accédez à https://127.0.0.1:8000/test, puis affichez le code source de la page (Ctrl + U).
Recherchez dans le code source les occurrences de chartjs ou importmap et notez ce que vous observez.
Une solution
Vous devez être connecté pour voir le contenu.